home *** CD-ROM | disk | FTP | other *** search
/ Kit PC World De Ampliacion De Windows 95 / Kit PC World de ampliacion de Windows 95.iso / internet / sweeper / samples / docobj / readme.txt < prev    next >
Text File  |  1995-11-22  |  8KB  |  177 lines
  1. Notes for DocObjects Framer (Container) Sample
  2. Kraig Brockschmidt, kraigb@microsoft.com
  3. November 1995
  4.  
  5.  
  6.  
  7. Framer is intended to demonstrate simple OLE Document Objects hosting as
  8. a container.  That is, Framer demonstrates the basic support necessary to
  9. host DocObjects.  It is implemented according to the guidlines in the
  10. "Document Objects Specification" document and has been tested against
  11. Microsoft Word and Microsoft Excel as well as a few other OLE-enabled
  12. applications that do not support DocObjects.
  13.  
  14.  
  15. Framer itself has almost nothing in the way of its own user interface such
  16. as a more complete host would, such as the Office Binder.  Framer has these
  17. menu commands available:
  18.  
  19.     Command     Description
  20.     ----------------------------------------------------------------------
  21.     File Open   Displays a File Open dialog and allows the user to select
  22.                 a file.  Framer will attempt to activate a DocObject for
  23.                 the file.  Failing that it will create a standard
  24.                 embedded object and activate it in a separate window.
  25.                 This command is disabled when an object already exists.
  26.                 File/Close must be used before creating another object.
  27.  
  28.     File Close  Closes the DocObject that is currently open; if the object
  29.                 is just an embedding it will destroy that object which has
  30.                 the effect of closing the server as well.  Try opening
  31.                 a .BMP file (which should activate PaintBrush, for instance)
  32.                 and use Close to see the effect.
  33.  
  34.     File Exit   Performs File/Close if necessary and terminates Framer.
  35.  
  36.     Help About  Displays Framer's About box.  This command exists to
  37.                 demonstrate DocObject Help menu merging.
  38.  
  39.  
  40. Whenever Framer knows it has an object it displays a small message in its
  41. client area to remind you that you have to File/Close before creating another.
  42.  
  43.  
  44. Creating and Activating an Object
  45. ---------------------------------
  46. When you "Open" a file in Framer, the code call OleCreateFromFile to create
  47. an embedded object from the contents of the file.  This has two possible
  48. results:
  49.  
  50.     1.  An embedded object with a real OLE server behind it.
  51.     2.  A package object managed by Packager
  52.  
  53. The next step Framer takes is to activate the object with IOleObject::DoVerb
  54. passing OLEIVERB_SHOW.
  55.  
  56. If the object is a package object, then packager will launch the file or
  57. execute the command line in it as it should.  This will generally display
  58. another window (like notepad for a TXT file) that is completely disconnected
  59. from Framer.  Using File/Close in Framer will not affect this other window
  60. as that will only destroy the Package object itself.  You'll have to
  61. manually close the other applications.
  62.  
  63. If the object is a real embedded object, then one of two things will happen
  64. upon activation:
  65.  
  66.     1.  If the object doesn't know about DocObjects, it is activated in
  67.         another window.  Using File/Close in this case will close the server.
  68.         Closing the server itself will cause Framer to do the equivalent
  69.         of File/Close, which frees the object and re-enables File/Open.
  70.         See CImpIIAdviseSink::OnClose in iadvsink.cpp.  The closing
  71.         sequence is in CFrame::Close in framer.cpp.
  72.  
  73.     2.  If the object is a DocObject, then it will start the DocObject
  74.         activation sequence, primarily by calling IOleDocumentSite::ActivateMe
  75.         which is found in idocsite.cpp.  Inside this member, Framer
  76.         then performs the standard sequence of document object activation
  77.         steps.  After these steps a DocObject will be fully interactive;
  78.         using File/Close on the menu, which Framer still owns, will
  79.         deactivate the object through CFrame::Close which performs the
  80.         same set of steps as in #1 above.
  81.  
  82.  
  83.  
  84. Help Menu Merging
  85. -----------------
  86.  
  87. Framer implements the container side of the Help menu merging protocol
  88. described in the Document Object Specification.  This involves the members
  89. CFrame::InsertMenus, CFrame::SetMenu, and CFrame::RemoveMenus.  The
  90. InsertMenus method will install Framer's Help menu in the correct location
  91. on the shared menu.  The container-side popup used here is loaded from
  92. Framer's resources on startup in CFrame::Init.
  93.  
  94. Inside CFrame::SetMenu, Framer checks if there's more than one item on
  95. the menu added in InsertMenus.  If so, then Framer remembers this fact
  96. for later message handling.  Otherwise Framer removes this menu from the
  97. shared menu entirely as the DocObject itself isn't using this shared
  98. capability.
  99.  
  100. Inside CFrame::RemoveMenus, Framer simply makes sure that its own Help
  101. menu is removed as it should be.
  102.  
  103. The really interesting stuff happens in FrameWndProc (framer.cpp) in the
  104. WM_INITMENU, WM_INITMENUPOPUP, WM_MENUSELECT, and WM_COMMAND cases.  Inside
  105. WM_INITMENU Framer clears a flag that indicates whether the last popup menu
  106. that was being used was the object's additions to the Help menu.  Inside
  107. WM_MENUSELECT, Framer checks if the originating menu is a popup and if so,
  108. it checks if that popup is on the shared "Help" popup, and if that is also
  109. true then Framer checks if the item being used is the first one or some
  110. other one.  The first item is what Framer knows to be its own Help item, so
  111. it just handles the messages as usual.  Otherwise the user is working with
  112. a DocObject-owned menu, so Framer sets the flag m_fInObjectHelp variable
  113. to TRUE and forwards the message to the object's window (available from
  114. IOleInPlaceObject::GetWindow).
  115.  
  116. As long as m_fInObjectHelp is set, Framer will forward WM_COMMAND,
  117. WM_INITMENUPOPUP, and WM_MENUSELECT messages.  As soon as another
  118. WM_MENUSELECT message is seen for another non-object menu, then Framer
  119. will reset the flag and begin processing messages once again itself.
  120.  
  121. In this way you'll see, with Microsoft Word for example, the correct
  122. behavior of a shared Help popup.
  123.  
  124.  
  125.  
  126.  
  127.  
  128. Known Feature Limitations
  129. -------------------------
  130. 1.  Framer does not print so it does not use the IPrint interface nor does
  131.     it implement IContinueCallback.
  132.  
  133. 2.  Framer does nothing with command targets.
  134.  
  135. 3.  Framer does not forward owner-draw menu messages to the object which
  136.     means that if owner-draw menus are used in a DocObject help menu,
  137.     this sample will not work correctly.
  138.  
  139. 4.  Framer does not provide for actually saving any changes made to a
  140.     DocObject.  Because a DocObject is an embedding, Framer has to provide
  141.     an instance of IStorage through IPersistStorage::InitNew or ::Load.  It
  142.     does this using a temporary Compound File that is deleted when Framer
  143.     exits.  Therefore any changes made to the data in the DocObject will
  144.     simply be discarded.
  145.  
  146.  
  147. Potential for Better UI
  148. -----------------------
  149.  
  150. The item #4 above takes a little more explanation.  When OleCreateFromFile is
  151. used in the File/Open command, Framer is making a COPY of the file contents.
  152. When a DocObject is activated with this content, the DocObject has a copy
  153. of the file contents, not the contents of the file itself.  Therefore any
  154. changes made there will not be reflected back into the original file, although
  155. Framer's UI suggests that this should happen.
  156.  
  157. A real DocObject container like the Office Binder actually stores all the
  158. object data in its own Compound File, not as separate files.  If one needs
  159. to have a DocObject save into a separate file, then the container needs to
  160. either use command-targets or has to call IPersistFile::Save to accomplish
  161. this step.
  162.  
  163. In short, DocObjects is not about activating the apps that manipulate files;
  164. it's about activating embedded *documents* saved within the container file
  165. *as if* those documents were stand alone.
  166.  
  167. Framer's UI, which is really inappropriate for DocObjects, exists as it does
  168. for simplicity's sake.
  169.  
  170. A more appropraite container application would maintain its own "files" in
  171. which it collected data from a number of other "documents" which are stored
  172. simply as embedded objects.  The Office Binder does exactly this, where
  173. a "Binder" is a Compound File with sub-storages for each "section" in the
  174. document.
  175.  
  176. Certainly with some more work on UI, Framer could become such an application.
  177.